Generate the network config from the roster instead of comparing it - #237

Closes #233. Closes #194.

LibRainDeploy.supportedNetworkConfigs() becomes the single statement of the
supported network set — name, chain id, explorer url and default endpoint.
LibRainDeployConfig emits [rpc_endpoints], [etherscan] and the
.env.example endpoint variables from it and splices each between its markers;
BuildScript.run() generates both files. supportedNetworks() is now the
roster's names.

That closes #194 by removing its subject rather than answering it. #194 said
nothing in the suite could make the foundry.toml config assertions fail: they
compared two hand-maintained statements of one set, and no test could drive
either side. With both sides written from one list there is nothing left to
compare, so testSupportedNetworksAreFullyConfigured is deleted — and with it
checkNetworksConfigured, checkEtherscanEntriesResolvable and
EtherscanEntryUnresolvable, which #229 had just moved the comparison's body
into.

Enforcement moves to Git is clean, the mechanism already holding
src/generated/: a tree whose config has drifted from the roster it pins fails
the job every push runs.

foundry refuses to write its own config

forge script ./script/Build.sol cannot write the project root's
foundry.toml — "access to foundry.toml is not allowed", a guard on the path
that no fs_permissions grant and no spelling of the path gets past, refusing
writeFile, writeLine and copyFile alike. So the fs_permissions change
#233 asked for (read → read-write on ./foundry.toml) is not the one that
works.

Reads are allowed, which is what makes the splice possible. run() reads each
file, splices its blocks and writes the result to .staged-config/;
script/build.sh installs each staged file onto the file of that name at the
root. That hook is rainix's own rainix-copy-artifacts consumer hook, which
runs outside any devshell, after the regeneration and before the git diff
that fails a stale tree. It needs no forge, no nix and no --ffi; granting
--ffi is the alternative and is not taken, because it would be granted to
every consumer's build rather than to this one step.

A repo with no script/build.sh is refused — BuildHookMissing — because
nothing else installs a staged file, and generating for such a repo would write
the roster where nothing reads it while the config went on saying whatever it
said, green.

Staging also retires the race #233 flagged as a requirement: nothing under
forge test can race a rewrite of the config every other test reads, because
nothing rewrites it.

what generation cannot settle

Whether a declared chain id is the one the bound endpoint reports is a claim
about the world rather than about the text, and chain is what --verify
submits. So RainDeployVerifyChain.testSupportedNetworkChainIdsAreBound forks
every supported network and compares block.chainid against the roster.

merging #229

main's #229 strengthened the reads this deletes, so the merge decides between
them everywhere the two meet, and generation wins: prose and assertions that
read foundry.toml back are the generator reading its own output. Kept from
#229: its reasoning about what a wrong chain costs, and its property that
every entry is checked and not only the first — ported to the roster as
testChainIdChecksEveryEntry. testRunCallsEveryHookThatRegenerates becomes
testRunCallsEveryGenerator: run() now also calls regenerateConfig, which
is deliberately not a hook, so the set it enumerates is every internal
function that can write rather than the internal virtual ones.

consumer impact

A repo inheriting BuildScript has to:

• copy script/build.sh, and gitignore .staged-config;
• carry the markers in its own foundry.toml and .env.example, once each,
  begin before end — everything outside them stays the consumer's, and the
  build neither reads nor moves it;
• keep fs_permissions on ./foundry.toml and ./.env.example at read, and
  add read-write on ./.staged-config and read on ./script/build.sh.

A consumer that called checkNetworksConfigured or
checkEtherscanEntriesResolvable by hand loses them. What replaces the
assertion is that the sections are written rather than checked.

Updated after merging main. This paragraph previously said the roster is
deliberately not overridable, on the reasoning that a repo able to narrow it
would verify fewer chains with nothing red. #261 landed the opposite —
supportedNetworks() is an overridable hook, so verification is scoped to the
networks a declaration names — and that is what the merge reconciles:

• supportedNetworkConfigs() is the catalogue: the facts about each network
  this package knows, and not overridable.
• declaredNetworkConfigs(networks) selects catalogue entries by declared name,
  in declaration order. Which of them a repo emits is overridable, through
  the one hook Scope verification to the networks the declaration names #261 added and no second statement of the set.
• A declared name with no catalogue entry reverts NetworkNotInCatalogue. That
  named refusal is what replaces the membership comparison, and it is why a
  network still cannot arrive in a consumer's config by anything but a version
  bump: narrowing can only ever select from what the bump brought.

BuildScript inherits RainDeploySuitesBase so the generator reads that same
hook. A same-signature virtual of its own would be a second statement of the
set, and because supportedNetworks() has a body it would force every
consumer's Build contract to write a disambiguating override.

#261's testConfigIsHeldToTheDeclaredNetworks is renamed to
BuildScriptNarrowNetworks.t.sol and re-expressed against the generated output,
keeping its name and its arbitrum message: a generator that ignored the
declaration fails on the alias rather than on a text diff. Nothing #261 added
was deleted.

QA

• Discriminating tests: testRpcEndpointsSectionIsTheRoster,
  testEtherscanSectionStatesChainOnEveryEntry,
  testEtherscanSectionEntriesAreResolvable,
  testEtherscanSectionOfTheSupportedNetworksIsResolvable,
  testEtherscanSectionZeroChainIdReverts,
  testEnvExampleSectionIsTheRosterDefaults, testVariableNamesAreUppercased,
  testEmptyRosterReverts, the ten testSplice* / testWrite* cases over the
  marker splice and the staged write, testStagedPathsAreNamedAsTheFilesTheyInstallOver,
  testWriteStagedConfigWithoutBuildHookReverts, testRunStagesTheNetworkConfig,
  testRunCallsEveryGenerator, testCutReleaseLeavesTheConfigAlone,
  testChainIdChecksEveryEntry, testChainIdEmptyRosterReverts,
  testSupportedNetworksAreTheRosterNames, testSupportedNetworkChainIds,
  testSupportedNetworkExplorerUrls. None of these can be run against base to
  fail there: LibRainDeployConfig, BuildScript.regenerateConfig and the
  SupportedNetwork roster they bind are added by this PR, so the suite does not
  compile on origin/main at all. Discrimination is shown by mutation instead —
  each line below is reverted to a shape base behaves as, and a named test fails.
• Mutations applied: mutation-probe over
  /home/thedavidmeister/code/scratch/fix-233-mutants.toml, baseline green at
  585 passed / 0 failed, 7 applied, 7 KILLED, 0 survived, 0 no-run, 0 harness
  errors.
  • RainDeployVerifyChain.checkChainIds: if (declared != reported) ->
    if (false) (the mismatch never reverts) -> testChainIdChecksEveryEntry,
    testChainIdIsReadFromTheForkedEndpoint, testChainIdMismatchReverts,
    testZoltuFactoryCodehash.
  • RainDeployVerifyChain.checkChainIds: if (declared != reported) ->
    if (true) (every match reverts) -> testChainIdMatchPasses.
  • RainDeployVerifyChain.checkChainIds: i < networks.length -> i < 1
    (only the first roster entry is checked) -> testChainIdChecksEveryEntry.
  • RainDeployVerifyChain.checkChainIds: if (networks.length == 0) ->
    if (false) (an empty roster passes having forked nothing) ->
    testChainIdEmptyRosterReverts.
  • BuildScript.run(): regenerateConfig(); deleted (run stops generating the
    config) -> testEveryHookIsReachedFromAnEntryPoint,
    testRunCallsEveryGenerator, testRunStagesTheNetworkConfig.
  • BuildScript.run(): recordRoot(); added beside it (run holds a call that
    generates nothing) -> testRunCallsEveryGenerator.
  • LibRainDeployConfig.etherscanSection: '}", chain = ', vm.toString(networks[i].chainId) -> '}"' (the generated entry states no
    chain, which is The config check passes an [etherscan] entry that takes verification down for every network #192's bug re-introduced on the generating side) ->
    testEtherscanSectionEntriesAreResolvable,
    testEtherscanSectionOfTheSupportedNetworksIsResolvable. The first pass
    scored this KILLED but named no killer, because its fail-pattern did not
    match forge's failure line for these two; re-probing this mutant alone with
    a widened pattern named them, same KILLED verdict.
• Oracle: for the generator, string literals written out in
  test/src/lib/LibRainDeployConfig.t.sol rather than concatenated the way the
  source concatenates — an expectation built by the source's own spelling would
  pass for any spelling, including a broken one — over a fixture roster
  alpha/beta/gamma that names no real network, so nothing passes against
  this repo's own config by accident. For run()'s wiring, the compiler's AST
  for the base contract, enumerating the generators the base declares rather
  than a hand-kept list, so a generator added and left uncalled fails without
  the test being touched. For the chain ids, the forked endpoint's own
  block.chainid, which is the world rather than the text. The intent oracle is
  Generate the network config sections from supportedNetworks() instead of comparing them #233's: RainDeployVerifySnapshot's NatSpec that the config sections "MUST be
  EXACTLY supportedNetworks(), which makes the three lists one".
• Category check: Generate the network config sections from supportedNetworks() instead of comparing them #233 asks for (a) [rpc_endpoints], (b) [etherscan] with
  each chain id, and (c) .env.example generated from the roster, (d) delimited
  so hand-written config around them survives, (e) from a hook in run(),
  (f) enforced by Git is clean, (g) the membership assertions removed, (h) a
  fork test on block.chainid with a real subject, (i) fs_permissions on
  ./foundry.toml moved read -> read-write, and (j) no test racing the rewrite.
  Covered: a, b, c, d, e, f, g, h, j. NOT covered, deliberately: (i) — forge
  refuses to write the project root's foundry.toml whatever fs_permissions
  says, so the grant stays read and script/build.sh installs from
  .staged-config/; staging is also what settles (j), since nothing rewrites
  the config under forge test at all. Nothing in the suite can make the foundry.toml config assertions fail #194 asks that the config assertions be
  capable of failing; covered by removing them, their subject being the
  comparison this generates away.

🤖 Generated with Claude Code

https://claude.ai/code/session_01V8ViHcKLVk2YoS2joH4HdN

Summary by CodeRabbit

• New Features

  • Network configuration for RPC endpoints, explorers, and environment examples is generated from the declared network list during builds.
  • Builds reject network names that aren’t in the supported catalogue and verify chain IDs against every declared network.

• Documentation

  • Updated setup guidance explains generated configuration, staged file installation, build commands, and filesystem permissions.